#' Kaplan-Meier Plot

#'

#' @description `r lifecycle::badge("stable")`

#'

#' @param df (`data.frame`)\cr data set containing all analysis variables.

#' @param variables (named `list`)\cr variable names. Details are:

#'   * `tte` (`numeric`)\cr variable indicating time-to-event duration values.

#'   * `is_event` (`logical`)\cr event variable. `TRUE` if event, `FALSE` if time to event is censored.

#'   * `arm` (`factor`)\cr the treatment group variable.

#'   * `strat` (`character` or `NULL`)\cr variable names indicating stratification factors.

#' @param control_surv (`list`)\cr parameters for comparison details, specified by using

#'   the helper function [`control_surv_timepoint`]. Some possible parameter options are:

#'   * `conf_level` (`proportion`)\cr confidence level of the interval for survival rate.

#'   * `conf_type` (`string`)\cr "plain" (default), "log", "log-log" for confidence interval type,

#'     see more in [survival::survfit()]. Note that the option "none" is no longer supported.

#' @param data (`data.frame`)\cr survival data as pre-processed by `h_data_plot`.

#' @param xticks (`numeric`, `number`, or `NULL`)\cr numeric vector of ticks or single number with spacing

#'   between ticks on the x axis. If `NULL` (default), [labeling::extended()] is used to determine

#'   an optimal tick position on the x axis.

#' @param yval (`string`)\cr value of y-axis. Options are `Survival` (default) and `Failure` probability.

#' @param censor_show (`flag`)\cr whether to show censored.

#' @param xlab (`string`)\cr label of x-axis.

#' @param ylab (`string`)\cr label of y-axis.

#' @param title (`string`)\cr title for plot.

#' @param footnotes (`string`)\cr footnotes for plot.

#' @param col (`character`)\cr lines colors. Length of a vector should be equal

#'   to number of strata from [survival::survfit()].

#' @param lty (`numeric`)\cr line type. Length of a vector should be equal

#'   to number of strata from [survival::survfit()].

#' @param lwd (`numeric`)\cr line width. Length of a vector should be equal

#'   to number of strata from [survival::survfit()].

#' @param pch (`numeric`, `string`)\cr value or character of points symbol to indicate censored cases.

#' @param size (`numeric`)\cr size of censored point, a class of `unit`.

#' @param max_time (`numeric`)\cr maximum value to show on X axis. Only data values less than or up to

#'   this threshold value will be plotted (defaults to `NULL`).

#' @param font_size (`number`)\cr font size to be used.

#' @param ci_ribbon (`flag`)\cr draw the confidence interval around the Kaplan-Meier curve.

#' @param ggtheme (`theme`)\cr a graphical theme as provided by `ggplot2` to control outlook of the Kaplan-Meier curve.

#' @param annot_at_risk (`flag`)\cr compute and add the annotation table reporting the number of patient at risk

#'   matching the main grid of the Kaplan-Meier curve.

#' @param annot_surv_med (`flag`)\cr compute and add the annotation table on the Kaplan-Meier curve estimating the

#'   median survival time per group.

#' @param annot_coxph (`flag`)\cr add the annotation table from a [survival::coxph()] model.

#' @param annot_stats (`string`)\cr statistics annotations to add to the plot. Options are

#'   `median` (median survival follow-up time) and `min` (minimum survival follow-up time).

#' @param annot_stats_vlines (`flag`)\cr add vertical lines corresponding to each of the statistics

#'   specified by `annot_stats`. If `annot_stats` is `NULL` no lines will be added.

#' @param control_coxph_pw (`list`)\cr parameters for comparison details, specified by using

#'   the helper function [control_coxph()]. Some possible parameter options are:

#'   * `pval_method` (`string`)\cr p-value method for testing hazard ratio = 1.

#'     Default method is "log-rank", can also be set to "wald" or "likelihood".

#'   * `ties` (`string`)\cr method for tie handling. Default is "efron",

#'     can also be set to "breslow" or "exact". See more in [survival::coxph()]

#'   * `conf_level` (`proportion`)\cr confidence level of the interval for HR.

#' @param position_coxph (`numeric`)\cr x and y positions for plotting [survival::coxph()] model.

#' @param position_surv_med (`numeric`)\cr x and y positions for plotting annotation table estimating median survival

#'   time per group.

#'

#' @name kaplan_meier

NULL

#' Kaplan-Meier Plot

#'

#' @description `r lifecycle::badge("stable")`

#'

#' From a survival model, a graphic is rendered along with tabulated annotation

#' including the number of patient at risk at given time and the median survival

#' per group.

#'

#' @return a `grob` of class `gTree`.

#'

#' @inheritParams grid::gTree

#' @inheritParams kaplan_meier

#' @inheritParams argument_convention

#'

#' @export

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(ggplot2)

#' library(survival)

#' library(grid)

#' library(nestcolor)

#'

#' df <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   mutate(is_event = CNSR == 0)

#' variables <- list(tte = "AVAL", is_event = "is_event", arm = "ARMCD")

#'

#' # 1. Example - basic option

#'

#' res <- g_km(df = df, variables = variables)

#' res <- g_km(df = df, variables = variables, yval = "Failure")

#' res <- g_km(

#'   df = df,

#'   variables = variables,

#'   control_surv = control_surv_timepoint(conf_level = 0.9),

#'   col = c("grey25", "grey50", "grey75")

#' )

#' res <- g_km(df = df, variables = variables, ggtheme = theme_minimal())

#' res <- g_km(df = df, variables = variables, ggtheme = theme_minimal(), lty = 1:3)

#' res <- g_km(df = df, variables = variables, max = 2000)

#' res <- g_km(

#'   df = df,

#'   variables = variables,

#'   annot_stats = c("min", "median"),

#'   annot_stats_vlines = TRUE

#' )

#'

#' # 2. Example - Arrange several KM curve on a single graph device

#'

#' # 2.1 Use case: A general graph on the top, a zoom on the bottom.

#' grid.newpage()

#' lyt <- grid.layout(nrow = 2, ncol = 1) %>%

#'   viewport(layout = .) %>%

#'   pushViewport()

#'

#' res <- g_km(

#'   df = df, variables = variables, newpage = FALSE, annot_surv_med = FALSE,

#'   vp = viewport(layout.pos.row = 1, layout.pos.col = 1)

#' )

#' res <- g_km(

#'   df = df, variables = variables, max = 1000, newpage = FALSE, annot_surv_med = FALSE,

#'   ggtheme = theme_dark(),

#'   vp = viewport(layout.pos.row = 2, layout.pos.col = 1)

#' )

#'

#' # 2.1 Use case: No annotations on top, annotated graph on bottom

#' grid.newpage()

#' lyt <- grid.layout(nrow = 2, ncol = 1) %>%

#'   viewport(layout = .) %>%

#'   pushViewport()

#'

#' res <- g_km(

#'   df = df, variables = variables, newpage = FALSE,

#'   annot_surv_med = FALSE, annot_at_risk = FALSE,

#'   vp = viewport(layout.pos.row = 1, layout.pos.col = 1)

#' )

#' res <- g_km(

#'   df = df, variables = variables, max = 2000, newpage = FALSE, annot_surv_med = FALSE,

#'   annot_at_risk = TRUE,

#'   ggtheme = theme_dark(),

#'   vp = viewport(layout.pos.row = 2, layout.pos.col = 1)

#' )

#'

#' # Add annotation from a pairwise coxph analysis

#' g_km(

#'   df = df, variables = variables,

#'   annot_coxph = TRUE

#' )

#'

#' g_km(

#'   df = df, variables = c(variables, list(strat = "SEX")),

#'   font_size = 15,

#'   annot_coxph = TRUE,

#'   control_coxph = control_coxph(pval_method = "wald", ties = "exact", conf_level = 0.99),

#'   position_coxph = c(0.4, 0.5)

#' )

#'

#' # Change position of the treatment group annotation table.

#' g_km(

#'   df = df, variables = c(variables, list(strat = "SEX")),

#'   font_size = 15,

#'   annot_coxph = TRUE,

#'   control_coxph = control_coxph(pval_method = "wald", ties = "exact", conf_level = 0.99),

#'   position_surv_med = c(1, 0.7)

#' )

#' }

g_km <- function(df,

                 variables,

                 control_surv = control_surv_timepoint(),

                 col = NULL,

                 lty = NULL,

                 lwd = .5,

                 censor_show = TRUE,

                 pch = 3,

                 size = 2,

                 max_time = NULL,

                 xticks = NULL,

                 xlab = "Days",

                 yval = c("Survival", "Failure"),

                 ylab = paste(yval, "Probability"),

                 title = NULL,

                 footnotes = NULL,

                 draw = TRUE,

                 newpage = TRUE,

                 gp = NULL,

                 vp = NULL,

                 name = NULL,

                 font_size = 12,

                 ci_ribbon = FALSE,

                 ggtheme = nestcolor::theme_nest(),

                 annot_at_risk = TRUE,

                 annot_surv_med = TRUE,

                 annot_coxph = FALSE,

                 annot_stats = NULL,

                 annot_stats_vlines = FALSE,

                 control_coxph_pw = control_coxph(),

                 position_coxph = c(0, 0.05),

                 position_surv_med = c(0.9, 0.9)) {

  }

  )

  )

  )

      )

        )

          )

      }

    }

        )

      }

    }

  }

    # This is the content of the table that will be below the graph.

      )

    } else {

      )

    }

    )

  }

        # Title.

          )

        },

        # The Kaplan - Meier curve (top-right corner).

        ),

        # Survfit summary table (top-right corner).

            )

          )

        },

              )

            )

          )

        },

        # Add the y-axis annotation (top-left corner).

        ),

        # Add the x-axis annotation (second row below the Kaplan Meier Curve).

        ),

        # Add the legend.

        ),

        # Add the table with patient-at-risk numbers.

          )

        },

          )

        },

          # Add the x-axis for the table.

          )

        },

        # Footnotes.

            ),

          )

        }

      )

    )

    )

  } else {

    )

  }

}

#' Helper function: tidy survival fit

#'

#' @description`r lifecycle::badge("stable")`

#'

#' Convert the survival fit data into a data frame designed for plotting

#' within `g_km`.

#'

#' @description `r lifecycle::badge("stable")`

#'

#' This starts from the [broom::tidy()] result, and then:

#' - post-processes the `strata` column into a factor,

#' - extends each stratum by an additional first row with time 0

#' and probability 1 so that downstream plot lines start at those coordinates,

#' - adds a `censor` column,

#' - filters the rows before `max_time`.

#'

#' @inheritParams kaplan_meier

#' @param fit_km (`survfit`)\cr result of [survival::survfit()].

#' @param armval (`string`)\cr used as strata name when treatment arm

#' variable only has one level. Default is "All".

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#'

#' # Test with multiple arms

#' tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .) %>%

#'   h_data_plot()

#'

#' # Test with single arm

#' tern_ex_adtte %>%

#'   filter(PARAMCD == "OS", ARMCD == "ARM B") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .) %>%

#'   h_data_plot(armval = "ARM B")

#' }

#'

#' @export

h_data_plot <- function(fit_km,

                        armval = "All",

                        max_time = NULL) {

    )

  } else {

  }

      # nolint start

      # nolint end

      )

    }

  )

  }

}

#' Helper function: x tick positions

#'

#' @description`r lifecycle::badge("stable")`

#'

#' Calculate the positions of ticks on the x-axis. However, if `xticks` already

#' exists it is kept as is. It is based on the same function `ggplot2` relies on,

#' and is required in the graphic and the patient-at-risk annotation table.

#'

#' @inheritParams kaplan_meier

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#'

#' data <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .) %>%

#'   h_data_plot()

#'

#' h_xticks(data)

#' h_xticks(data, xticks = seq(0, 3000, 500))

#' h_xticks(data, xticks = 500)

#' h_xticks(data, xticks = 500, max_time = 6000)

#' h_xticks(data, xticks = c(0, 500), max_time = 300)

#' h_xticks(data, xticks = 500, max_time = 300)

#' }

#'

#' @export

h_xticks <- function(data, xticks = NULL, max_time = NULL) {

    } else {

    }

    } else {

    }

  } else {

      )

    )

  }

}

#' Helper function: KM plot

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Draw the Kaplan-Meier plot using `ggplot2`.

#'

#' @inheritParams kaplan_meier

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#'

#' fit_km <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .)

#' data_plot <- h_data_plot(fit_km = fit_km)

#' xticks <- h_xticks(data = data_plot)

#' gg <- h_ggkm(

#'   data = data_plot,

#'   censor_show = TRUE,

#'   xticks = xticks,

#'   xlab = "Days",

#'   yval = "Survival",

#'   ylab = "Survival Probability",

#'   title = "Survival"

#' )

#' gg

#' }

#'

#' @export

h_ggkm <- function(data,

                   xticks = NULL,

                   yval = "Survival",

                   censor_show,

                   xlab,

                   ylab,

                   title,

                   footnotes = NULL,

                   max_time = NULL,

                   lwd = 1,

                   lty = NULL,

                   pch = 3,

                   size = 2,

                   col = NULL,

                   ci_ribbon = FALSE,

                   ggtheme = nestcolor::theme_nest()) {

  # change estimates of survival to estimates of failure (1 - survival)

  }

      )

    ) +

  }

  }

  }

  }

      ),

    ) +

      )

  }

    } else {

    }

  }

  }

  )

}

#' `ggplot` Decomposition

#'

#' @description `r lifecycle::badge("stable")`

#'

#' The elements composing the `ggplot` are extracted and organized in a

#' list containing:

#' the panel (`panel`),

#' the y-axis and its label (`yaxis`, `ylab`),

#' idem for the x-axis (`xaxis`, `xlab`),

#' the legend (`guide`).

#'

#' @param gg (`ggplot`)\cr a graphic to decompose.

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#' library(grid)

#'

#' fit_km <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .)

#' data_plot <- h_data_plot(fit_km = fit_km)

#' xticks <- h_xticks(data = data_plot)

#' gg <- h_ggkm(

#'   data = data_plot,

#'   yval = "Survival",

#'   censor_show = TRUE,

#'   xticks = xticks, xlab = "Days", ylab = "Survival Probability",

#'   title = "tt",

#'   footnotes = "ff"

#' )

#'

#' g_el <- h_decompose_gg(gg)

#' grid::grid.newpage()

#' grid.rect(gp = grid::gpar(lty = 1, col = "red", fill = "gray85", lwd = 5))

#' grid::grid.draw(g_el$panel)

#'

#' grid::grid.newpage()

#' grid.rect(gp = grid::gpar(lty = 1, col = "royalblue", fill = "gray85", lwd = 5))

#' grid::grid.draw(with(g_el, cbind(ylab, yaxis)))

#' }

#'

#' @export

h_decompose_gg <- function(gg) {

  )

}

#' Helper: KM Layout

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Prepares a (5 rows) x (2 cols) layout for the Kaplan-Meier curve.

#'

#' @inheritParams kaplan_meier

#' @param g_el (`list` of `gtable`)\cr list as obtained by `h_decompose_gg()`.

#' @param annot_at_risk (`flag`)\cr compute and add the annotation table

#'   reporting the number of patient at risk matching the main grid of the

#'   Kaplan-Meier curve.

#' @export

#'

#' @details

#' The layout corresponds to a grid of two columns and five rows of unequal

#' dimensions. Most of the dimension are fixed, only the curve is flexible and

#' will accommodate with the remaining free space.

#' - The left column gets the annotation of the `ggplot` (y-axis) and the

#'   names of the strata for the patient at risk tabulation.

#'   The main constraint is about the width of the columns which must allow the

#'   writing of the strata name.

#' - The right column receive the `ggplot`, the legend, the x-axis and the

#' patient at risk table.

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#'

#' fit_km <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .)

#' data_plot <- h_data_plot(fit_km = fit_km)

#' xticks <- h_xticks(data = data_plot)

#' gg <- h_ggkm(

#'   data = data_plot,

#'   censor_show = TRUE,

#'   xticks = xticks, xlab = "Days", ylab = "Survival Probability",

#'   title = "tt", footnotes = "ff", yval = "Survival"

#' )

#' g_el <- h_decompose_gg(gg)

#' lyt <- h_km_layout(data = data_plot, g_el = g_el, title = "t", footnotes = "f")

#' grid.show.layout(lyt)

#' }

#'

h_km_layout <- function(data, g_el, title, footnotes, annot_at_risk = TRUE) {

        )

      )

    )

  )

  }

  )

  )

  }

  } else {

  }

    )

  )

}

#' Helper: Patient-at-Risk Grobs

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Two Graphical Objects are obtained, one corresponding to row labeling and

#' the second to the number of patient at risk.

#'

#' @inheritParams kaplan_meier

#' @param annot_tbl (`data.frame`)\cr annotation as prepared

#'   by [survival::summary.survfit()] which includes the number of

#'   patients at risk at given time points.

#' @param xlim (`numeric`)\cr the maximum value on the x-axis (used to

#'   ensure the at risk table aligns with the KM graph).

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#' library(grid)

#'

#' fit_km <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .)

#'

#' data_plot <- h_data_plot(fit_km = fit_km)

#'

#' xticks <- h_xticks(data = data_plot)

#'

#' gg <- h_ggkm(

#'   data = data_plot,

#'   censor_show = TRUE,

#'   xticks = xticks, xlab = "Days", ylab = "Survival Probability",

#'   title = "tt", footnotes = "ff", yval = "Survival"

#' )

#'

#' # The annotation table reports the patient at risk for a given strata and

#' # time (`xticks`).

#' annot_tbl <- summary(fit_km, time = xticks)

#' if (is.null(fit_km$strata)) {

#'   annot_tbl <- with(annot_tbl, data.frame(n.risk = n.risk, time = time, strata = "All"))

#' } else {

#'   strata_lst <- strsplit(sub("=", "equals", levels(annot_tbl$strata)), "equals")

#'   levels(annot_tbl$strata) <- matrix(unlist(strata_lst), ncol = 2, byrow = TRUE)[, 2]

#'   annot_tbl <- data.frame(

#'     n.risk = annot_tbl$n.risk,

#'     time = annot_tbl$time,

#'     strata = annot_tbl$strata

#'   )

#' }

#'

#' # The annotation table is transformed into a grob.

#' tbl <- h_grob_tbl_at_risk(data = data_plot, annot_tbl = annot_tbl, xlim = max(xticks))

#'

#' # For the representation, the layout is estimated for which the decomposition

#' # of the graphic element is necessary.

#' g_el <- h_decompose_gg(gg)

#' lyt <- h_km_layout(data = data_plot, g_el = g_el, title = "t", footnotes = "f")

#'

#' grid::grid.newpage()

#' pushViewport(viewport(layout = lyt, height = .95, width = .95))

#' grid.rect(gp = grid::gpar(lty = 1, col = "purple", fill = "gray85", lwd = 1))

#' pushViewport(viewport(layout.pos.row = 4, layout.pos.col = 2))

#' grid.rect(gp = grid::gpar(lty = 1, col = "orange", fill = "gray85", lwd = 1))

#' grid::grid.draw(tbl$at_risk)

#' popViewport()

#' pushViewport(viewport(layout.pos.row = 4, layout.pos.col = 1))

#' grid.rect(gp = grid::gpar(lty = 1, col = "green3", fill = "gray85", lwd = 1))

#' grid::grid.draw(tbl$label)

#' }

#'

#' @export

h_grob_tbl_at_risk <- function(data, annot_tbl, xlim) {

    ),

      ),

    )

  )

    ),

    )

  )

            ),

          )

        )

      )

    ),

            ),

          )

        )

      )

    )

  )

}

#' Helper Function: Survival Estimations

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Transform a survival fit to a table with groups in rows characterized

#' by N, median and confidence interval.

#'

#' @inheritParams h_data_plot

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#'

#' adtte <- tern_ex_adtte %>% filter(PARAMCD == "OS")

#' fit <- survfit(

#'   form = Surv(AVAL, 1 - CNSR) ~ ARMCD,

#'   data = adtte

#' )

#' h_tbl_median_surv(fit_km = fit)

#' }

#'

#' @export

h_tbl_median_surv <- function(fit_km, armval = "All") {

  } else {

  }

  )

  )

}

#' Helper Function: Survival Estimation Grob

#'

#' @description `r lifecycle::badge("stable")`

#'

#' The survival fit is transformed in a grob containing a table with groups in

#' rows characterized by N, median and 95% confidence interval.

#'

#' @inheritParams kaplan_meier

#' @param ttheme (`list`)\cr see [gridExtra::ttheme_default()].

#' @param x a `numeric` value between 0 and 1 specifying x-location.

#' @param y a `numeric` value between 0 and 1 specifying y-location.

#' @inheritParams h_data_plot

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#' library(grid)

#'

#' grid::grid.newpage()

#' grid.rect(gp = grid::gpar(lty = 1, col = "pink", fill = "gray85", lwd = 1))

#' tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .) %>%

#'   h_grob_median_surv() %>%

#'   grid::grid.draw()

#' }

#'

#' @export

h_grob_median_surv <- function(fit_km,

                               armval = "All",

                               x = 0.9,

                               y = 0.9,

                               ttheme = gridExtra::ttheme_default()) {

  )

    )

  )

}

#' Helper: Grid Object with y-axis Annotation

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Build the y-axis annotation from a decomposed `ggplot`.

#'

#' @param ylab (`gtable`)\cr the y-lab as a graphical object derived from

#'   a `ggplot`.

#' @param yaxis (`gtable`)\cr the y-axis as a graphical object derived from

#'   a `ggplot`.

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#' library(grid)

#'

#' fit_km <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(form = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .)

#' data_plot <- h_data_plot(fit_km = fit_km)

#' xticks <- h_xticks(data = data_plot)

#' gg <- h_ggkm(

#'   data = data_plot,

#'   censor_show = TRUE,

#'   xticks = xticks, xlab = "Days", ylab = "Survival Probability",

#'   title = "title", footnotes = "footnotes", yval = "Survival"

#' )

#'

#' g_el <- h_decompose_gg(gg)

#'

#' grid::grid.newpage()

#' pvp <- grid::plotViewport(margins = c(5, 4, 2, 20))

#' pushViewport(pvp)

#' grid::grid.draw(h_grob_y_annot(ylab = g_el$ylab, yaxis = g_el$yaxis))

#' grid.rect(gp = grid::gpar(lty = 1, col = "gray35", fill = NA))

#' }

#'

#' @export

h_grob_y_annot <- function(ylab, yaxis) {

      ),

    )

  )

}

#' Helper Function: Pairwise CoxPH table

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Create an `rtable` of pairwise stratified or unstratified CoxPH analysis results.

#'

#' @inheritParams g_km

#' @export

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#'

#' adtte <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   mutate(is_event = CNSR == 0)

#'

#' h_tbl_coxph_pairwise(

#'   df = adtte,

#'   variables = list(tte = "AVAL", is_event = "is_event", arm = "ARM"),

#'   control_coxph_pw = control_coxph(conf_level = 0.9)

#' )

#' }

h_tbl_coxph_pairwise <- function(df,

                                 variables,

                                 control_coxph_pw = control_coxph()) {

    )

      ),

    )

}

#' Helper Function: CoxPH Grob

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Grob of `rtable` output from [h_tbl_coxph_pairwise]

#'

#' @inheritParams h_grob_median_surv

#' @param ... arguments will be passed to [h_tbl_coxph_pairwise()].

#' @param x a `numeric` value between 0 and 1 specifying x-location.

#' @param y a `numeric` value between 0 and 1 specifying y-location.

#' @export

#'

#' @examples

#' \dontrun{

#' library(dplyr)

#' library(survival)

#' library(grid)

#'

#' grid::grid.newpage()

#' grid.rect(gp = grid::gpar(lty = 1, col = "pink", fill = "gray85", lwd = 1))

#' data <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   mutate(is_event = CNSR == 0)

#' tbl_grob <- h_grob_coxph(

#'   df = data,

#'   variables = list(tte = "AVAL", is_event = "is_event", arm = "ARMCD"),

#'   control_coxph_pw = control_coxph(conf_level = 0.9), x = 0.5, y = 0.5

#' )

#' grid::grid.draw(tbl_grob)

#' }

h_grob_coxph <- function(...,

                         x = 0,

                         y = 0,

                         ttheme = gridExtra::ttheme_default(

                           base_size = 12,

                           padding = grid::unit(c(1, .5), "lines"),

                           core = list(bg_params = list(fill = c("grey95", "grey90"), alpha = .5))

                         )) {

      )

        )

      )

    },

      ))

          )

        )

      )

    }

  )

}

#' Multi-Variable Logistic Regression Table

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Layout creating function which summarizes a logistic variable regression for binary outcome with

#' categorical/continuous covariates in model statement. For each covariate category (if categorical)

#' or specified values (if continuous), present degrees of freedom, regression parameter estimate and

#' standard error (SE) relative to reference group or category. Report odds ratios for each covariate

#' category or specified values and corresponding Wald confidence intervals as default but allow user

#' to specify other confidence levels. Report p-value for Wald chi-square test of the null hypothesis

#' that covariate has no effect on response in model containing all specified covariates.

#' Allow option to include one two-way interaction and present similar output for

#' each interaction degree of freedom.

#' Note: For the formula, the variable names need to be standard dataframe column name without

#' special characters.

#'

#' @inheritParams argument_convention

#' @param drop_and_remove_str string to be dropped and removed

#'

#' @examples

#' library(dplyr)

#' library(broom)

#'

#' adrs_f <- tern_ex_adrs %>%

#'   filter(PARAMCD == "BESRSPI") %>%

#'   filter(RACE %in% c("ASIAN", "WHITE", "BLACK OR AFRICAN AMERICAN")) %>%

#'   mutate(

#'     Response = case_when(AVALC %in% c("PR", "CR") ~ 1, TRUE ~ 0),

#'     RACE = factor(RACE),

#'     SEX = factor(SEX)

#'   )

#' formatters::var_labels(adrs_f) <- c(formatters::var_labels(tern_ex_adrs), Response = "Response")

#' mod1 <- fit_logistic(

#'   data = adrs_f,

#'   variables = list(

#'     response = "Response",

#'     arm = "ARMCD",

#'     covariates = c("AGE", "RACE")

#'   )

#' )

#' mod2 <- fit_logistic(

#'   data = adrs_f,

#'   variables = list(

#'     response = "Response",

#'     arm = "ARMCD",

#'     covariates = c("AGE", "RACE"),

#'     interaction = "AGE"

#'   )

#' )

#'

#' df <- tidy(mod1, conf_level = 0.99)

#' df2 <- tidy(mod2, conf_level = 0.99)

#'

#' # flagging empty strings with "_"

#' df <- df_explicit_na(df, na_level = "_")

#' df2 <- df_explicit_na(df2, na_level = "_")

#'

#' result1 <- basic_table() %>%

#'   summarize_logistic(

#'     conf_level = 0.95,

#'     drop_and_remove_str = "_"

#'   ) %>%

#'   build_table(df = df)

#' result1

#'

#' result2 <- basic_table() %>%

#'   summarize_logistic(

#'     conf_level = 0.95,

#'     drop_and_remove_str = "_"

#'   ) %>%

#'   build_table(df = df2)

#' result2

#'

#' @export

summarize_logistic <- function(lyt,

                               conf_level,

                               drop_and_remove_str = "") {

  # checks

}

#' Fit for Logistic Regression

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Fit a (conditional) logistic regression model.

#'

#' @inheritParams argument_convention

#' @param data (`data.frame`)\cr the data frame on which the model was fit.

#' @param response_definition (`string`)\cr the definition of what an event is in terms of `response`.

#'   This will be used when fitting the (conditional) logistic regression model on the left hand

#'   side of the formula.

#'

#' @section Model Specification:

#'

#' The `variables` list needs to include the following elements:

#' \describe{

#'   \item{arm}{treatment arm variable name.}

#'   \item{response}{the response arm variable name. Usually this is a 0/1 variable.}

#'   \item{covariates}{this is either `NULL` (no covariates) or a character vector of covariate variable names.}

#'   \item{interaction}{this is either `NULL` (no interaction) or a string of a single covariate variable name already

#'     included in `covariates`. Then the interaction with the treatment arm is included in the model.

#'   }

#' }

#'

#' @examples

#' library(dplyr)

#'

#' adrs_f <- tern_ex_adrs %>%

#'   filter(PARAMCD == "BESRSPI") %>%

#'   filter(RACE %in% c("ASIAN", "WHITE", "BLACK OR AFRICAN AMERICAN")) %>%

#'   mutate(

#'     Response = case_when(AVALC %in% c("PR", "CR") ~ 1, TRUE ~ 0),

#'     RACE = factor(RACE),

#'     SEX = factor(SEX)

#'   )

#' formatters::var_labels(adrs_f) <- c(formatters::var_labels(tern_ex_adrs), Response = "Response")

#' mod1 <- fit_logistic(

#'   data = adrs_f,

#'   variables = list(

#'     response = "Response",

#'     arm = "ARMCD",

#'     covariates = c("AGE", "RACE")

#'   )

#' )

#' mod2 <- fit_logistic(

#'   data = adrs_f,

#'   variables = list(

#'     response = "Response",

#'     arm = "ARMCD",

#'     covariates = c("AGE", "RACE"),

#'     interaction = "AGE"

#'   )

#' )

#'

#' @export

fit_logistic <- function(data,

                         variables = list(

                           response = "Response",

                           arm = "ARMCD",

                           covariates = NULL,

                           interaction = NULL,

                           strata = NULL

                         ),

                         response_definition = "response") {

  )

  }

  }

    } else {

    }

  }